fix(spec)!: refuse a padded grouping.fields[].field name at the producer instead of handing three renderers a lookup that always misses - #17498

Fixes #17360

Clause-②: yes — fixed by the ruling, not by the diff's size. This is a spec narrowing, and the objectui#8285 precedent says a spec narrowing declares yes. needs:contract-review rides on both carriers (already on the card; hung on this PR too), the changeset is minor with a **BREAKING** note, and the ADR-0087 disposition is registered. It needs an at-tier verdict on the head that lands — ⛔ this PR is a draft and the at-tier verdict is the domain:spec seat's to commission, so nothing here flips ready, enqueues, or arms auto-merge.

Implemented by an os-dev subagent in session session_01MkQhmuuJAVDjmeWNixwDDH, inheriting the claim and assignee from the domain:spec execution seat's Claim: comment on #17360 (no second claim posted, assignee untouched).

The ruling

Ruling C on objectui#7347, maintainer verbatim 「其他同意」, decision batch #110 item 5: refuse at the producer. GroupingFieldSchema.field gets a non-padded pattern with a refusal naming the field and the offending spelling.

⛔ Not .trim(). A trimming schema makes ' a ' and 'a' silently equivalent, which is the consumer-tolerance direction AGENTS.md #0.1 refuses. objectui's harvester trim stays as defence-in-depth; nothing is removed there. The sibling groupByField axis is explicitly not this card and is untouched.

⭐ The "reuse the vocabulary if one exists" conditional — I measured it and took the FIRST branch, which is not what I inherited

The ruling asks for a non-padded pattern "the same shape the field-name vocabulary already uses elsewhere in packages/spec if one exists — reuse it, do not invent a second".

The seat's hold notes measured that FieldNameSchema was retired under protocol 18, and concluded the conditional resolves to its second branch (define the pattern). I re-verified that against origin/main and half of it is right, but the conclusion is not — and the correction comes from the retired-def's own text:

packages/spec/src/migrations/entries/retired-defs/18.shared__FieldName.ts
  "No schema in either repo ever composed `FieldNameSchema`, so the promised brand
   safety was unobtainable. The real field-name contract is the inline
   `z.string().regex(/^[a-z_][a-z0-9_]*$/)` at `data/field.zod.ts` — untouched by
   this retirement."

So the branded schema is retired (confirmed: the retired-def entry and the semantic entry 18.branded-identifier-schemas-retired are both on origin/main), but a field-name vocabulary is alive and ubiquitous: /^[a-z_][a-z0-9_]*$/, spelled inline at 30+ sites including data/field.zod.ts:932 — the field name itself. The conditional therefore resolves to its first branch, and no protocol-18 retirement has to be re-opened to read it. ⛔ Nothing here revives the retired branded-identifier family — there is no 回翻 in this diff and the card did not have to be returned.

And then I did not adopt that vocabulary — measured, with the evidence:

grouping.fields[].field is authored as a field reference, not a machine name, and the repo proves it: packages/lint/src/validate-list-view-field-refs.test.ts:537 carries grouping: { fields: [{ field: 'owner.name' }] }, a dotted relationship path, in a test that asserts it produces no finding. /^[a-z_][a-z0-9_]*$/ refuses owner.name. Adopting it would have reddened an in-tree grouping fixture — which the acceptance criteria name as a finding to report, not a reason to widen — and would have been a different, larger narrowing than the one ruled.

⇒ The pattern is non-padded only: /^(?:\S|\S[\s\S]*\S)?$/. Exactly what the ruling asked for, nothing wider, nothing narrower. Stated in the source docblock so the next reader does not have to re-derive it.

What changed

packages/spec/src/ui/view.zod.ts — anchored by content on export const GroupingFieldSchema (it happened to still be at :853, but nothing here depends on that):

• a module-level GROUPING_FIELD_NON_PADDED_PATTERN and a checkGroupingFieldName(raw) refusal builder, following this file's own house idiom for a dynamic per-value message (checkSubmitRedirectUrl + .superRefine), which is what lets the message name the offending spelling as well as the key;
• field gains the .superRefine, and its .describe() states the rule.

The refusal lands at grouping.fields[N].field — the offending element's own key — and reads, for ' business_unit ':

grouping.fields[].field names the field exactly as it is stored, with no leading or trailing whitespace — received " business_unit ". The group header query is compiled from this string verbatim … Write "business_unit". (ruled 2026-09-10.)

Deliberately left alone: the empty string still parses. A blank name is already refused loudly one layer down by compileListViewGroupQuery's grouping_field_blank (400, path ['grouping','fields',N,'field']); this narrowing exists for the silent case, and refusing the blank here too would be scope the ruling did not ask for.

Also: the ADR-0087 semantic entry 18.ui-list-view-grouping-field-padded-refused, registry.ts regenerated with gen:migration-registry (⛔ no hand edit — the insertion is at :10355, inside the os-generated semantic:18 markers at :5452/:10565), the changeset, and the regenerated content/docs/references/ui/view.mdx.

⭐ Acceptance — the fixture enumeration, which is the item that bites

Harvested with the TypeScript parser, not a grep — the tool's own predicate rather than a re-implementation:

Lit controls: business_unit present in the harvest; priority present (it is the GroupingFieldSchema.parse fixture that pass 1 structurally could not see, which is why pass 2 exists). Dark control: zz_no_such_grouping_field absent.

The one refused spelling is ' ' at packages/spec/src/ui/view-grouping-query.test.ts:507. It is a negative fixture handed straight to compileListViewGroupQuery with no Zod parse anywhere on its path, pinning that same grouping_field_blank refusal — so it is not a fixture that has to parse, and the producer now refuses it one layer earlier for the same reason. Zero in-tree fixtures redden, and the pattern was not widened to fit anything.

Pins added in view.test.ts: the by-name refusal at grouping.fields.1.field (asserted through ListViewSchema so the path is the real one), the six whitespace shapes, a not-a-trim arm, the 20 harvested spellings as an it.each table, and a lit/dark control test that also carries the discriminator (' owner.name' is refused) — because the accepting arms alone would pass just as well against the old bare z.string().

Verification

Reverse verification (ablation). Predicted direction: red. Removed the .superRefine and rebuilt nothing (the test resolves ./view.zod relatively — no dist on the path). On-disk proof before and after: injected-text count 2 to 0, git diff --stat HEAD non-empty. Result: 9 pins red, exactly the ruling's ones (× refuses a padded grouping field name BY NAME at grouping.fields[N].field, the six whitespace shapes, the not-a-trim arm, the lit/dark discriminator); the 20 accepting arms stayed green, which is the expected asymmetry. Restore leg via git checkout HEAD -- PATH under a trap … EXIT INT TERM with an absolute path, proven byte-identical: worktree blob 848f63fa33f3e63da434e59bcc51abcdbdfc8718 equals the HEAD blob.

The downstream three are run because an accept-set narrowing changes the runtime face even though the exported byte shape does not; their first run was the MODULE_NOT_FOUND class (unbuilt @objectstack/formula) and was re-run after building the closures rather than recorded as red.

NOT MEASURED, called out separately from red — neither is a finding:

• pnpm check:dual-build-cjs-loads — exit 3, PREREQUISITE NOT MET: 33 packages have no dist/. Needs a whole-monorepo build; declared to CI.
• pnpm check:type-check-debt — exit 3, PREREQUISITE NOT MET: @objectstack/metadata-core unbuilt, and the gate refuses to measure a different world. Its coverage half (check:type-check-coverage) ran green.

check:react-declaration-parity, run exactly as dispatched: exit 0, manifest sdui.manifest.json at the repository root (66910 bytes) — not the packages/spec path a literal $PWD gives you, which the gate itself rejects with a loud "this gate did NOT run". ⚠️ The snapshot's freshness relative to .objectui-sha remains unmeasured (#17405), so this green is about parity against the committed manifest, not about the manifest being current.

Two residuals I am not able to close from here and am therefore declaring rather than papering over: the gate derivation ran on a tree ~9 commits behind origin/main, and one file it derives from (scripts/measure-reserved-identity-name-census.mjs) changed in that range, so CI's re-derivation on the true merge base is the authority on the family set; and the 45 artifact-roster families, the 11 wide-population families and the 6 path-scheduled CI jobs are outside the derived total by construction.

⚠️ One thing the seat should know: the declared file face has a co-tenant

The claim's batch-independence line reads "measured disjoint from … every open PR at claim time". Re-checked at write time: PR #17298 (feat(spec)!: retire the type: 'page' list-view mount, open, mergeable_state: dirty) touches all three of view.zod.ts, view.test.ts and registry.ts.

I did not widen my face and I did not reorder anything. The hunks are disjoint by a wide margin — #17298's earliest view.zod.ts hunk is at :1629 against my :853, its earliest view.test.ts hunk at :3754 against my ~:2050, and registry.ts is generated and regenerates — so this merges cleanly rather than needing the serial hold that #17447 got. Recording it because the claim's reading of it was different from mine, and that is the seat's to arbitrate, not mine.

Generated by Claude Code